---
title: 项目结构
description: 一个对 Astro 项目基本文件结构的介绍。
---
import { FileTree } from '@astrojs/starlight/components';

你用 `create astro` CLI 向导所生成的新 Astro 项目中已经包括一些文件和文件夹。其他的将由你创建并添加到 Astro 的现有文件结构中

以下是 Astro 的项目结构，以及一些你将在新项目中发现的文件。

## 目录和文件

Astro 为你的项目提供了一个有想法的文件夹布局。每个 Astro 项目的根目录下都应该包括以下目录和文件：

- `src/*` - 你的项目源代码（组件、页面、样式、图片等）。
- `public/*` - 你的非代码、未处理的资源（字体、图标等）。
- `package.json` - 项目清单。
- `astro.config.mjs` - Astro 配置文件（推荐）。
- `tsconfig.json` - TypeScript 配置文件（推荐）。

### 项目树示例

常见的 Astro 项目目录可能看起来像这样：

<FileTree>
- public/
  - robots.txt
  - favicon.svg
  - my-cv.pdf
- src/
  - blog/
    - post1.md
    - post2.md
    - post3.md
  - components/
    - Header.astro
    - Button.jsx
  - images/
    - image1.jpg
    - image2.jpg
    - image3.jpg
  - layouts/
    - PostLayout.astro
  - pages/
    - posts/
      - [post].astro
    - about.astro
    - **index.astro**
    - rss.xml.js
  - styles/
    - global.css
  - content.config.ts
- astro.config.mjs
- package.json
- tsconfig.json
</FileTree>

### `src/`

`src/` 文件夹是大部分项目源代码所在的地方。这包括：

- [页面](/zh-cn/basics/astro-pages/)
- [布局](/zh-cn/basics/layouts/)
- [Astro 组件](/zh-cn/basics/astro-components/)
- [UI 框架组件（React 等）](/zh-cn/guides/framework-components/)
- [样式（CSS、Sass）](/zh-cn/guides/styling/)
- [Markdown](/zh-cn/guides/markdown-content/)
- [由 Astro 优化和处理的图像](/zh-cn/guides/images/)

Astro 处理、压缩和打包你的 `src/` 文件以创建最终传递到浏览器的网站。与静态的 `public/` 目录不同，你的 `src/` 文件是由 Astro 为你构建和处理的。

有些文件（如 Astro 组件）甚至不会按写入方式传递到浏览器，而是被渲染成静态 HTML。其他文件（如 CSS）则会被传递到浏览器，但可能被会压缩或与其他 CSS 文件打包在一起以提高性能。

:::tip
虽然本指南描述了 Astro 社区中使用的一些流行约定，但 Astro 保留的目录只有 `src/pages/`。你可以自由的以最适合自己的方式重命名和重新组织任何其他目录。
:::

### `src/pages`

[页面](/zh-cn/basics/astro-pages/)是一种用于创建新的页面的特殊组件。一个页面可以是一个 Astro 组件，也可以是表示站点某些页面内容的 Markdown 文件。

:::caution
`src/pages` 是 Astro 项目中**必须要有的**子目录。没有它，你的网站将没有任何页面或路径！
:::

### `src/components`

**组件**是你在 HTML 页面中可重复使用的代码单元。它可以是 [Astro 组件](/zh-cn/basics/astro-components/) 或是像 React 或 Vue 这样的[UI 框架组件](/zh-cn/guides/framework-components/)。通常将你项目中所有组件都分组放在这个文件夹中。

这是 Astro 项目约定俗成的，但不是必需的。你可以随意组织你的组件！

### `src/layouts`

[布局](/zh-cn/basics/layouts/)是定义一个或多个[页面](/zh-cn/basics/astro-pages/)共享的 UI 结构的 Astro 组件。

和 `src/components` 一样，这个目录也只是约定俗成，但不是必需的。

### `src/styles`

将 CSS 或 Sass 文件存储在 `src/styles` 目录中是一种常见的约定，但这不是必需的。只要你的样式位于 `src/` 目录中的某个位置并且正确导入，Astro 就会处理和压缩它们。

### `public/`

`public/` 目录用于项目中不需要在 Astro 构建过程中处理的文件和资源。这个文件夹中的文件将会被原封不动地复制到构建文件夹中，然后你的网站将被构建。

这种行为使 `public/` 非常适合用来存放不需要任何处理的常见资源，如某些图片和字体，或特殊文件，如 `robots.txt` 和 `manifest.webmanifest`。

你也可以把 CSS 和 JavaScript 放在 `public/` 目录中，但要注意这些文件不会在最终构建中被打包或压缩。

:::tip
一般而言，你自己编写的 CSS 或 JavaScript 都应该放在 `src/` 目录下。
:::

### `package.json`

JavaScript 包管理器用它来管理依赖关系。它也定义了通常用于运行 Astro 的脚本（例如：`npm run dev`、`npm run build`）。

在 `package.json` 中可以指定[两种依赖关系](https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file)：`dependencies` 和 `devDependencies`。在大多数情况下它们效果一样，Astro 在构建时需要所有依赖，而你的包管理器则会同时安装这两种依赖。我们建议把所有的依赖项放在 `dependencies` 中，只有在你发现有特殊需要后，再使用 `devDependencies`。

如果想要为你的项目创建新的 `package.json` 文件时遇到困难，请查看[手动安装](/zh-cn/install-and-setup/#手动安装)中的说明。

### `astro.config.mjs`

该文件在每个入门模板中都会生成，它包括你的 Astro 项目的配置。你可以在这里指定要使用的集成、构建选项、服务器选项以及其他内容。

Astro 支持多种 JavaScript 配置文件格式：`astro.config.js`、`astro.config.mjs`、`astro.config.cjs` 以及 `astro.config.ts`。大多数情况下，我们更建议使用 `.mjs`，如果你想在配置文件中编写 TypeScript 则建议使用 `.ts`。

TypeScript 配置文件加载是使用 [`tsm`](https://github.com/lukeed/tsm) 来进行处理的，并且会遵循你项目中的 `tsconfig` 选项。

参见[配置参考](/zh-cn/reference/configuration-reference/)以了解完整的详细信息。

### `tsconfig.json`

该文件在每个入门模板中都会生成，它包括你的 Astro 项目的 TypeScript 配置项。如果没有 `tsconfig.json` 文件，编辑器将不完全支持某些功能（如 npm 包的导入）。

参见 [TypeScript 指南](/zh-cn/guides/typescript/)了解关于配置的更多细节。
